home *** CD-ROM | disk | FTP | other *** search
/ Software of the Month Club 2000 October / Software of the Month - Ultimate Collection Shareware 277.iso / pc / PROGRAMS / UTILITY / WINLINUX / DATA1.CAB / programs_-_usrdoc / POWERD-2.0 / README.{_2 < prev    next >
Text File  |  1999-09-17  |  10KB  |  269 lines
  1.          POWERD-2.0
  2.         ==========
  3.  
  4.             Alessandro Rubini  --  rubini@ipvvis.unipv.it
  5.  
  6.  
  7. Note that this document is updated less frequently than the soft.  If
  8. this doc tells something is there, it is there. If it tells something
  9. is still missing, it may be there as well. I hope to remember to
  10. upgrade README before releasing the true 2.0, though I may forget to.
  11.  
  12.                         September 25th 1995
  13.  
  14. What's new
  15. ----------
  16.  
  17. This release of powerd is meant to replace and upgrade the simple
  18. powerd-1.1 which comes in the package "SysVInit-2.5" by Miquel van
  19. Smoorenburg. I didn't manage to reach Miquel to agree about distribution.
  20. I hope he's happy with this program. Miquel, are you there?
  21.  
  22. The main goal of this program is to avoid hacking the source code of
  23. powerd to tailor it to the specific ups used. powerd-2.0 is designed to
  24. handle different sources of information, and its modular design
  25. should allow ease extension by those who have a peculiar setup.
  26.  
  27. The powerd daemon can be told to accept connection on a TCP socket, so that
  28. other powerd's can benefit from an ups-aware one. Powerd can connect to
  29. another powerd as a client. This is a better approach than a broadcast
  30. notification of power status, because the latter can be easily faked.
  31.  
  32. Since some ups's allow shutting down, to preserve their battery in
  33. order to correctly handle glitches when the power comes back, you can
  34. specify to shutdown the ups by toggling some lines on the serial
  35. cable. If you know other ways to shutdown the ups, please tell me,
  36. and I'll implement it (or send me the code to get a note in the
  37. CREDITS file ;-)
  38.  
  39. A "powerd.conf" file is used to exactly specify how to behave.
  40.  
  41.  
  42. An Alternative
  43. --------------
  44.  
  45. If you're going to control a single computer from your ups, perhaps you'd
  46. better look at genpower, by Tom Webster (on sunsite and mirrors in the
  47. directory system/UPS). Tom's package is very well documented and quite
  48. easy to setup. However, it doesn't manage network connections.
  49.  
  50. Since we (Tom and me) are planning to merge the two packages, we'd be
  51. happy to have some feedback about pros and cons of each product. Unfortunately,
  52. it could take some time before we have time to merge our works.
  53.  
  54.  
  55.  
  56. Agents
  57. ------
  58.  
  59. An "agent" is a program section which monitors a source of information,
  60. and tells the main program what to do. Powerd uses a single agent to
  61. get information about powerd lines, but several of them are compiled in,
  62. to allow runtime selection. The following agents are supported:
  63.  
  64. * Network client: powerd connects to another host and waits for
  65.     information. It uses an udp socket, and can be configured to poll
  66.     the server (every few minutes or so) in order to "keep connected"
  67.     the connectionless link. Powerd can act as a network server,
  68.     independently of the agent being used.
  69.  
  70. * Serial line: the daemon monitors a serial wire. This is what
  71.     powerd-1.1 used to do, and works with relay-base ups's.
  72.     You can specify which line to monitor and what is the meaning of
  73.     the line voltages.
  74.  
  75. * Fifo: powerd monitors a fifo node on the filesystem. This is the easiest way
  76.     to fake power glitches in order to test shutdown and reboot of the
  77.     system. Note that current kernels deny writing to a fifo on a 
  78.     read-only filesystem. This is a problem in complete testings.
  79.     The fifo agent is best used in "disabled" mode, to drive a network
  80.     server.
  81.  
  82. * External program: spawn an executable and monitor its standard output.
  83.     The program is executed through "popen", so you can specify a
  84.     full commandline, complete with stdin redirection.
  85.     This agent is meant for those who have
  86.     an ups which talks to a real serial connection, and to relief me from
  87.     serial setup. Obviously, if you want to write an agent for a true
  88.     serial connection, I'll    include it in the next powerd.
  89.  
  90.  
  91.  
  92. What's missing
  93. --------------
  94.  
  95. The interface to "init" suits SysVInit-2.4 for Linux and later.  I'd
  96. like to make this tool as portable as possible, but I've no spare
  97. workstations to shut down -- when I'm so lucky to be root I can't
  98. shutdown anything, except my own Linux box. The source is almost ready
  99. to be portable, I just lack information to do it.
  100.  
  101. I would like to ease addition and removal of agents, by specifying a
  102. clean interface between the main body and the agents (I'm dreaming
  103. abot dynamic loading). Currently, the main problem is the centralized
  104. static variable-set.  I don't know if I'll ever do it, I suppose it
  105. depends on the amount of feedback I get.
  106.  
  107.  
  108.  
  109. Powerd.conf
  110. -----------
  111.  
  112. Browse the sample configuration file. Some skeletal information is in the
  113. manual page, but the sample file is still the reliable doc.
  114.  
  115.  
  116.  
  117. Command line
  118. ------------
  119.  
  120. The following invocations work:
  121.  
  122. powerd
  123.     Read /etc/powerd.conf and go for it. the configuration file
  124.     can specify any of the following behaviours, if needed. Ideally,
  125.     your bootstrap files should invoke powerd with no arguments, while
  126.     the commandline is meant to be used for testing purposes.
  127.  
  128. powerd [anything] -host <host> <port>
  129.     Be a client. Wait for the strings "OK" and "FAIL". The
  130.     configuration file is not read.
  131.  
  132. powerd [anything] -port port
  133.     Be the server. This is independent of the agent used, which is
  134.     specified by the previous options or by the configuration
  135.     file.
  136.  
  137. powerd <file> [options]
  138.     If "file" is a regular one, use it as config file; if it is a char
  139.     device, emulate powerd-1.1 (monitor DCD going low, after asserting
  140.     DTR high); if it is a fifo, use the fifo agent on it.
  141.  
  142. powerd "<variable>=<value>" [...]
  143.     Any agument embedding an equal sign is used like it was a line
  144.     of the configuration file.
  145.  
  146. As an example, the following two commandlines make a fifo-controlled
  147. client/server pair to try workings
  148.  
  149.  
  150. ./powerd debug=y disabled=y readfifo=/var/run/upsctl -port 2065
  151.  
  152. ./powerd debug=y disabled=y delay=0 pollingstep=2 -host localhost 2065
  153.  
  154.  
  155.  
  156. Installing
  157. ----------
  158.  
  159. Just "make" and "make install", the executable will go in /sbin and
  160. the configuration file in /etc.  The man page is not installed (my
  161. fault).  To install under /usr/sbin and /usr/etc just "make
  162. PREFIX=/usr" and "make install PREFIX=/usr". Same for /usr/local;
  163. specifying the prefix during compilation is only needed to instruct
  164. the program to use the right powerd.conf as a default case. Note that
  165. powerd and powerd.conf must reside in the root filesystem in order fro
  166. your computer to be able to wake up from singleuser-ness.
  167.  
  168. During installation, an existing powerd executable will be
  169. orerwritten, while an existing configuration file will be preserved.
  170.  
  171.  
  172.  
  173. How to setup your bootstrap files
  174. ---------------------------------
  175.  
  176. You should modify your initialization files in the following way.
  177. I use the file names of my old slackware installation, you should 
  178. modify the corresponding files of your system. Each file gets its role
  179. from its appearing in /etc/inittab.
  180.  
  181.  
  182. /etc/rc.d/rc.K (the file appearing in the "su:S:wait:" inittab line)
  183.  
  184.     This script is executed when going down to single-user mode.
  185.     You should invoke powerd at the end of this script: you'll
  186.     need the daemon to awake the system when power is back, or to
  187.     shutdown the ups to actually put the system to sleep. If the ups
  188.     is not shutdown, your computer will turn off at battery exaustion.
  189.  
  190. /etc/rc.d/rc.S (the file appearing in the "si:S:sysinit" inittab line)
  191.  
  192.     This is the first script that gets executed at system boot.
  193.     You should invoke powerd at the end of this script. rc.S is not
  194.     executed during recovery from a single-user shutdown, but when that
  195.     happens the daemon invoked by rc.K is still alive and well.
  196.  
  197. /etc/rc.d/rc.M (the file appearing in the "rc:45:wait" inittab line)
  198.  
  199.     Remember to put a "/sbin/swapon -a" in *this* file.
  200.     Slackware puts it in rc.S (wise thing, anyways, but not sufficient).
  201.     Otherwise you'll recover from a power fail without any swap
  202.     (my small machine just hangs). There's no need to invoke powerd from
  203.     this file, it would be a second instance of the program.
  204.     To avoid an error message of "device busy" on first system boot,
  205.     you could use "/sbin/swapon -a 2> /dev/null" instead; otherwise
  206.     you could remove swapon invocation from rc.S. 
  207.  
  208.  
  209. The preferred way to invoke powerd from the rc files is the following:
  210.  
  211.     if [ -f /sbin/powerd ]; then
  212.         echo "Running powerd"
  213.         /sbin/powerd &
  214.     fi
  215.  
  216. It is important to put the daemon to the background, because
  217. if you forgot debugging enabled in /etc/powerd.conf you'll hang your computer
  218. before any login is spawned.
  219.  
  220.  
  221.  
  222. Testing your cable
  223. ------------------
  224.  
  225. If your ups is a relay-based one, it is most likely that you don't
  226. know how your serial cable has to be set up. The program
  227. "setserialbits", in this distribution, is a small yet effective tool
  228. to probe your serial connection. The program should be
  229. self-explicative, so I won't discuss it here.
  230.  
  231. Sure you need some knowledge of how to setup a serial line. Since
  232. Tom's documentation is really complete (see above: "An alternative").
  233. I won't duplicate the information here. SysVInit-2.50 holds some
  234. explanation of it as well, and the UPS-HOWTO may be another helpful
  235. document.
  236.  
  237.  
  238. Additional tips
  239. ---------------
  240.  
  241. The serial line doesn't need to have a dedicated interrupt line,
  242. you can add "setserial /dev/cua2 irq 0" or sth similar to your rc files.
  243.  
  244. Be careful about the owner and the permission of the serial port, fifo
  245. or external daemon you use. Malicious users could fake a powerfail to
  246. bring the system down.
  247.  
  248. If your ups cannot be turned off, you'd better not put the console
  249. display under the ups: when the computer is in single-user mode, the
  250. console holds a root shell. An unattended console with a root shell is 
  251. something slightly unsecure. I didn't analyze the problem, but I think
  252. this is harwired in init.
  253.  
  254. Be careful about time delays if you use the network to shutdown multiple
  255. computers: you should be careful not to turn off the ups before *all*
  256. of your computers unmount their disks. This time interval depends on
  257. the pollingstep of the clients. A future release of powerd may
  258. handle some client-server dialog to agree about this. 
  259.  
  260.  
  261. Enjoy
  262. -----
  263.  
  264. Go for it. Please report any bugs to me.
  265.  
  266.  
  267. /alessandro
  268.  
  269.